home *** CD-ROM | disk | FTP | other *** search
/ Complete Linux / Complete Linux.iso / docs / devel / tcl / tclx7_31.z / tclx7_31 / tcldev / tclX7.3a-p1 / INSTALL < prev    next >
Encoding:
Text File  |  1993-12-03  |  15.5 KB  |  394 lines
  1. EXTENDED TCL SOURCE DIRECTORY HIERARCHY
  2. =======================================
  3.  
  4. Building the Extended Tcl requires access to built Tcl and Tk source
  5. directories.  Their location relative to the tclX7.3a directory must be
  6. configured by editing tclX7.3a/Config.mk.  The default is to place tclX7.3a
  7. in a directory parallel to the Tcl and Tk distributions:
  8.  
  9.                    tcl7.3      tk3.6      tclX7.3a
  10.  
  11.  
  12. The following directories are included under the tclX7.3a directory:
  13.  
  14.     o man - Unformatted manual pages for TclX.
  15.  
  16.     o src - The main source for TclX.
  17.  
  18.     o osSupport - Library routines required by TclX that may not be available
  19.       on all Unix versions.
  20.  
  21.     o tclsrc - Tcl source that is built into the standard Tcl package library.
  22.       The makefile also handles generation of help files.
  23.  
  24.     o tests - Tests for TclX.
  25.  
  26.     o tclhelp - The Tcl and TclX help files.  These can be rebuilt from the
  27.       manual pages if necessary.
  28.  
  29.     o tksrc - A makefile that builds a version of the Tk wish shell containing
  30.       Extended Tcl.
  31.  
  32.     o tktclsrc - Tcl source that is built into the standard Tk package library.
  33.       The makefile also handles generation of help files.
  34.  
  35.     o tktests - Files used to test wishx.
  36.  
  37.     o tkhelp - The Tk help files.  These can be rebuilt from the manual pages
  38.       if necessary.
  39.  
  40.     o experimental - A directory of experimental and contributed Tcl source.
  41.       The code is not normally built as part of TclX.
  42.  
  43.     o tools - Tools used for building and installing TclX.
  44.  
  45.     o tclmaster - Tcl master directory.  All files required to run TclX are
  46.       built or copied into this directory.  The entire contents of this
  47.       directory are installed.  This directory is created by the build.
  48.  
  49.     o tkmaster - Tk master directory.  All files required to run Tk
  50.       are built or copied into this directory.  The entire contents of
  51.       this directory are installed.  This directory is created by the build.
  52.  
  53.  
  54. THE EXTENDED TCL INSTALLATION MODELS
  55. ====================================
  56.  
  57. Two installation models are supported by Extended Tcl.  You should decide which
  58. model you are going to use before building TclX.  We encourage use of the 
  59. "master directory" model, as it supports multiple versions of Extended Tcl and
  60. Tk being installed on the system at the same time and allows for easy copying
  61. to other systems.
  62.  
  63. Standard Installation Model
  64. ---------------------------
  65.  
  66. The standard model follows the GNU standards.  Two variables are defined
  67. by configure, "prefix" and "exec_prefix".  The variable "prefix" is the
  68. path that will contain the directories containing hardware and system
  69. independent files:
  70.  
  71.    o ${prefix}/tclX/7.3a - TclX runtime files.
  72.    o ${prefix}/tkX/3.6a - TkX runtime files.
  73.    o ${prefix}/include - Include files for TclX.
  74.    o ${prefix}/man - Manual pages for TclX.
  75.  
  76. The variable "exec_prefix" is the path that will contain the directories
  77. containing hardware and system dependent files:
  78.  
  79.    o ${exec_prefix}/bin - tcl, wishx and tclhelp programs.
  80.    o ${exec_prefix}/lib - libtclx.a and libtkx.a
  81.  
  82. Both "exec_prefix" and "prefix" default to "/usr/local".  All of these
  83. directories can be changed independently by editing "Config.mk".  To set
  84. the prefix directories:
  85.  
  86.     ./configure --prefix=/usr/site  --exec_prefix==/usr/site.cray
  87.  
  88. With the standard model, only Extended Tcl files are installed.  Its is
  89. assumed that the Tcl & Tk standard libraries, include files and manual
  90. pages have been installed.
  91.  
  92. Master Directory Installation Model
  93. -----------------------------------
  94.  
  95. The master directory model installs *all* files required by TclX (including
  96. files from the Tcl and Tk distributions) in master directories.  
  97.  
  98.    o ${prefix}/tclX/7.3a - TclX runtime files.
  99.    o ${prefix}/tclX/7.3a/include - Include files.
  100.    o ${prefix}/tclX/7.3a/man - Manual pages.
  101.    o ${prefix}/tclX/7.3a/bin - tcl program.
  102.    o ${prefix}/tclX/7.3a/lib - libtclx.a and libtcl.a
  103.  
  104.    o ${prefix}/tkX/3.6a - TkX runtime files.
  105.    o ${prefix}/tkX/3.6a/include - Include files.
  106.    o ${prefix}/tkX/3.6a/man - Manual pages.
  107.    o ${prefix}/tkX/3.6a/bin - wishx and tclhelp programs.
  108.    o ${prefix}/tkX/3.6a/lib - libtkx.a and libtk.a
  109.  
  110. Symbolic links are then built for executables from the standard locations
  111. to the files in the master directory.
  112.  
  113.    /usr/local/bin/tcl   -> /usr/local/tclX/7.3a/bin/tcl
  114.    /usr/local/bin/wishx -> /usr/local/tkX/3.6a/bin/wishx
  115.  
  116.  
  117. If the --arch=ARCH option was specified to configure (see below), the bin and
  118. lib files are stored in architecture-dependent directories with the specified
  119. architecture as a suffix to the directory name:
  120.  
  121.    o ${prefix}/tclX/7.3a/bin.arch
  122.    o ${prefix}/tclX/7.3a/lib.arch
  123.    o ${prefix}/tkX/3.6a/bin.arch
  124.    o ${prefix}/tkX/3.6a/lib.arch
  125.  
  126. You may defined "arch" to be any string you like; it might include OS type or
  127. version as well as processor architecture.
  128.  
  129. Symbolic links are still build from the standard locations of the machines
  130. of specified architecture to the master directory:
  131.  
  132.    /usr/local/bin/tcl   -> /usr/local/tclX/7.3a/bin.sparc/tcl
  133.    /usr/local/bin/wishx -> /usr/local/tkX/3.6a/bin.sparc/wishx
  134.         
  135. HOW TO BUILD EXTENDED TCL
  136. =========================
  137.  
  138.     o Configure and compile Tcl 7.3 following the instructions that come with
  139.       Tcl.  You do not need to install it.
  140.  
  141.     o If you are going to be using Tk and want to build an Extended Tcl wish
  142.       shell (wishx), configure and compile Tk 3.6.  You do not need to install
  143.       it.
  144.  
  145.     o Enter ./configure to run the configure script.  The following options are
  146.       recognized by the TclX configure script:
  147.  
  148.         o --srcdir=DIR
  149.           If you are using a make that supports VPATH (e.g. GNU make) you can
  150.           use this to compile in a separate directory from the source.
  151.           Note: The source directory must be clean, it can't contain a built
  152.           copy of TclX.
  153.  
  154.         o --arch=ARCH
  155.           If your are using the master directory installation model, this
  156.           specifies the a suffix to use for the architecture-dependent
  157.           directories under the master directory.  Use the --execprefix
  158.           option for installing architecture-dependent under the standard
  159.           installation model.
  160.  
  161.         o --prefix=PREFIX
  162.           Directory under which the "include" and "man" directories are
  163.           found for installation. 
  164.  
  165.         o --execprefix=EXECPREFIX
  166.           Directory under which the "bin" and "lib" directories are
  167.           found for installation.  
  168.  
  169.     o Edit Config.mk in the build directory following the instructions in the
  170.       file.  If the --srcdir option to configure is used, it is copied from
  171.       the source directory to the build directory.  This file is used to
  172.       specify values that can't be figured out by the configure script.  This
  173.       includes the location of the Tcl and Tk distributions.  It's also used
  174.       to specify the sections that the Tcl manual pages are to be installed
  175.       in.
  176.  
  177.     o Note that the site specific installation options should be set in
  178.       Config.mk before compiling.  It is especially important to set the value
  179.       for TCL_MASTERDIR and TK_MASTERDIR in Config.mk before compiling TclX.
  180.       See the section on "Installing Extended Tcl" for more details.
  181.  
  182.     o Config.mk can be used to override several values that configure might
  183.       have gotten wrong or that you desire to be change (like gcc vs cc).
  184.  
  185.     o Now do a "make".  If all goes well, this will build an extended
  186.       "libtclx.a" and the "tcl" executable in the tclmaster directory.  If Tk
  187.       is requested, an extended "libtkx.a" and "wishx" executable will be
  188.       built in the tkmaster directory.
  189.  
  190.     o Until the Extended Tcl runtime files are installed, "tcl" and "wishx"
  191.       can't be run directly.  To run them before installation, use "runtcl" or
  192.       "runwishx".
  193.  
  194.     o Extended Tcl comes with help pages that are built from the Tcl 7.3 and
  195.       Tk 3.6 manual pages as well as the TclX manual page.  If you are building
  196.       TclX with a later version of Tcl or Tk, you might want to rebuild these
  197.       manual pages.  If new manual pages have been added, you can add them
  198.       by editing the files "tools/tclmanpages" and "tools/tkmanpages".
  199.       You must have nroff and the man macro package installed on your system
  200.       to build the manual pages.  Enter "make buildtclhelp" to build the
  201.       Tcl and TclX help pages and "make buildtkhelp" to build the Tk manual
  202.       pages or "make buildhelp" to build both.  If the help files are rebuilt,
  203.       another make should be done to copy them into the master directories.
  204.  
  205.     o Note that if you modify any files in the Tcl or Tk library directories
  206.       you need to do a "make clean" and a "make" to rebuild Extended Tcl,
  207.       as these changes are not detected by the TclX make files.
  208.  
  209.    We have a limited number of systems available to test Extended Tcl on,
  210. we need your help in supporting TclX on a wide range of platforms.  The nature
  211. of the functionality TclX supports mean a great deal of system dependent code.
  212. Thanks to all of those who have submitted configuration files and changes to
  213. TclX.
  214.  
  215. TESTING EXTENDED TCL
  216. ====================
  217.  
  218.    There are three sets of tests: the tests for Berkeley Tcl, the tests for
  219. Tk and the tests for Extended Tcl, which test both the new commands added by
  220. Extended Tcl and the procedures defined in the Extended Tcl procedure
  221. library.
  222.  
  223.     o Run both the Berkeley and TclX tests by typing "make test" in the
  224.       tclX7.3a directory.  The some of the UCB tests require a tcl shell with
  225.       added commands (tcltest in the tcl7.3 distribution).  Because the
  226.       Extended TCL shell (tcl) does not have these commands, the you will
  227.       receive warnings about not having the following commands:
  228.  
  229.         testasync
  230.         testcmdinfo
  231.         testdcall
  232.         testdstring
  233.         testlink
  234.  
  235.       Your will also receive warning about not having the following math
  236.       functions:
  237.  
  238.         T1
  239.         T2
  240.  
  241.     o To run the Tk tests with wishx, type "make tktest".  The tests require
  242.       a tcl shell with added commands (tcltest in the tcl7.3 distribution).
  243.       Because the Extended TCL shell (tcl) does not have these commands, the
  244.       following tests will not run:
  245.  
  246.         raise.test
  247.  
  248.     o The Extended Tcl tests may be run by themselves with "make extdtests".
  249.  
  250.     o If a test fails, please dig into the test and the C source for the
  251.       function being tested, fix the bug and mail us the change.  If you're
  252.       not inclined to do this, please report the problem, including the output
  253.       of the test, to tcl-project@neosoft.com.  Sometimes tests fail due to
  254.       problems in the system environment or bugs in that test rather than
  255.       problems with TclX.  Even if a few of the tests fail, you probably still
  256.       have a working TclX.  See the "Porting Notes" section of this document
  257.       for problems we have encountered.
  258.  
  259.     o If you're having trouble with the Berkeley tests, and you suspect that
  260.       the extensions might be involved, you can build a special minimal
  261.       version of Berkeley Tcl by cd'ing to the tcl7.3 directory and doing
  262.       a "make test".  Similarly, you can do "make test" in the tk3.6 directory.
  263.  
  264. INSTALLING EXTENDED TCL
  265. =======================
  266.  
  267. Standard Installation Model
  268. ---------------------------
  269.  
  270. To install Extended Tcl (and Tk if built) using the standard installation
  271. model, enter:
  272.  
  273.    su use-to-own-files
  274.    make install
  275.  
  276. to only install the executable and library files (useful for installing on
  277. a multi-architecture server that has the rest of TclX already installed):
  278.  
  279.    su use-to-own-files
  280.    make install-exec
  281.  
  282. Master Directory Installation Model
  283. -----------------------------------
  284. To install Extended Tcl (and Tk if built) using the master directory
  285. installation model, enter:
  286.  
  287.    su use-to-own-files
  288.    make install-master
  289.  
  290. to only install the executable and library files (useful for installing on
  291. a multi-architecture server that has the rest of TclX already installed):
  292.  
  293.    su use-to-own-files
  294.    make install-master-exec
  295.  
  296. SHARED LIBRARIES
  297. ================
  298.  
  299.    Shared libraries are not directly supported by the TclX build process,
  300. since the mechanisms for building them are not portable across Unix
  301. platforms.  See the file README.SHLIB for help in building shared libraries.
  302. This file is oriented towards Suns.  If you have instructions on other
  303. platforms, please contact us.
  304.  
  305.  
  306. INTEGRATING PATCHES
  307. ===================
  308.  
  309. TclX copies and recomplies the following files:
  310.  
  311.    ${TCL_UCB_SRC}/tcl7.3/tclCmdIL.c to src/tclCmdIL.c
  312.    ${TK_UCB_SRC/tk3.6/tkWindow.c to tksrc/tkWindow.c
  313.  
  314. If you patch either of these files, you must compile TclX.  The make rules
  315. should take care of recompiling the correct files.  If you patch any of the
  316. tcl or tk .h files, you should do a make clean and then a make of TclX.
  317.  
  318. These files are recompiled as they have compiled in paths to the library 
  319. directories, which are different under TclX.  We are talking with John
  320. Ousterhout about a solution.
  321.  
  322. PORTING NOTES
  323. =============
  324.  
  325. General:
  326.    o Flock tests hanging:  Problems have been encountered on some Sun
  327.      systems with the flock tests.  This might occur on other systems as
  328.      well.  These are probably due to an incorrectly configured NFS lockd.
  329.      The tests have been modified to try and report problems rather than
  330.      hang.  It might hang anyway, in this case, rename tests/flock.test to
  331.      tests/flock.bad to prevent them from being run.  If anyone can gives
  332.      any clues into what is going on, we would love to detect this.
  333.  
  334. DEC Ultrix:
  335.    o Several tests fail when Tcl is run on an NFS mounted file system.
  336.  
  337. SUN:
  338.    o Seen not on flock tests hanging under the "general" section.
  339.  
  340.     
  341. SOLARIS:
  342.    o message-cat-1.3 test appears to fail due to broken catopen.
  343.    o tcllib-4.1 test fails.
  344.  
  345. SCO:
  346.    o SCO Unix systems have a "ranlib" command that is used for Xenix cross-
  347.      development.  Pre-ODT 3.0 development systems, the command returns
  348.      an error if used on COFF files.  Many developers rename the command
  349.      to "xranlib" if they are not doing cross development.  Later versions
  350.      of the command return a warning if used on COFF binaries.
  351.  
  352. SGI:
  353.    o The strftime function does not work correctly on SGI (tested on
  354.      IRIX 4.0.5).  This is a known bug and will be fixed in the next IRIX
  355.      release.  The fmtclock command specifying the GMT argument (perhaps
  356.      only during daylight) returns a formated time that is one hour off.  This
  357.      causes the following clock tests to fail:
  358.  
  359.         clock-3.2
  360.         clock-4.0
  361.         clock-4.1
  362.      
  363.      If this is a problem to your application, add the following macro to your
  364.      Config.mk:
  365.  
  366.          LIBOBJS=strftime.o
  367.  
  368.      This will cause a functioning (but not internationalized) strftime
  369.      to be built and added to libtclx.a.
  370.  
  371. BSDI:
  372.    o The BSDI make is broken.  It does not correctly handle the setting of
  373.      ${MAKEFLAGS} and quits on an error when an empty make flags set is passed
  374.      to the next level of make.  GNU make is advised instead.  Use the
  375.      following make command to work around the problem:
  376.  
  377.           make -k MAKEFLAGS=k
  378.  
  379.    o Also seee the 386BSD/BSDI section below.
  380.  
  381. 386BSD/NetBSD:
  382.    o Expect round off errors in floating point math tests.
  383.    o Expect errors in floating point math error handling tests.
  384.    o Expect errors in format command tests.
  385.    o The installation of the manual pages fails because make can't handle
  386.      passing a empty string as an argument to a program (it deletes the
  387.      string).  Try GNU make.
  388.    o Also seee the 386BSD/BSDI section below.
  389.  
  390. 386BSD/BSDI
  391.    o There is some problem in the configure parsing of the --arch option.  
  392.      The syntax "./configure --arch=XXX" will not work, use
  393.      "./configure --arch XXX" instead.
  394.